TreeView (wfxTreeView)

(Note: Image support for TreeView has not yet been implemented)

Properties

Methods

Events

TreeNode (wfxTreeNode)

Properties

Methods

TreeNodeCollection (wfxTreeNodeCollection)

TreeSubNodeCollection (wfxTreeSubNodeCollection)

Properties

How to use the TreeView

Adding root and children nodes

The following example will create four root nodes. The fourth root node (Project 4), will have several children nodes. If the TreeView has the Sorted property set to True then the nodes and children nodes will automatically be sorted when they are added to the control.

dim as long root, node, subnode, subsubnode
root = frmMain.TreeView1.Nodes.Add("Project 1")
root = frmMain.TreeView1.Nodes.Add("Project 2")
root = frmMain.TreeView1.Nodes.Add("Project 13")
    
node = frmMain.TreeView1.Node(root).Nodes.Add("Project 6")
for i as long = 1 to 3
   subnode = frmMain.TreeView1.Node(root).Node(node).Nodes.Add("Project File" & i)
   for i as long = 1 to 2
      subsubnode = frmMain.TreeView1.Node(root).Node(node).Node(subnode).Nodes.Add("Sub Project File" & i)
      for i as long = 1 to 5
         frmMain.TreeView1.Node(root).Node(node).Node(subnode).Node(subsubnode).Nodes.Add("Sub Sub Project File" & i)
      next
   next
next

The above example just adds a text description to each new TreeNode. You can also specifiy an optional 32-bit Long integer that you can use for whatever purpose you wish.

frmMain.TreeView1.GetSelectedNode.Nodes.Add( "New Node", 10232 )

Deleting/Removing a TreeNode

' The following removes the first node off of the root using the collection:
frmMain.TreeView1.Nodes.Remove(0)

' Remove the node using the TreeNode Remove method:
frmMain.TreeView1.Node(0).Remove

' -or- (notice the use of ByRef)
Dim ByRef TreeNode = frmMain.TreeView1.Node(0)
TreeNode.Remove

' Every node also has child node collections, so to remove the first child node of the first root node then do this:
frmMain.TreeView1.Node(0).Nodes.Remove(0)

' Remove the currently selected node
frmMain.TreeView1.SelectedNode.Remove

Display a Popup Menu when Right Click on a TreeNode

Function frmMain_TreeView1_MouseDown( ByRef sender As wfxTreeView, ByRef e As EventArgs ) As LRESULT
   
   if e.RButton then
      ' Determine if we have clicked on a TreeNode
      dim as wfxPoint wpt = e.pt
      wpt.Convert( frmMain.TreeView1.hWindow )
      
      ' Only continue if the TreeNode is valid
      dim byref TreeNode as wfxTreeNode = sender.GetNodeAt( wpt )
      if TreeNode.hNode = 0 then exit function
      
      ' Ensure that the node right clicked on is now selected
      TreeNode.Selected = true 
      
      dim as wfxPopupMenu PopMenu
      PopMenu.AddItem( "Menu Option 1", 1 )
      PopMenu.AddItem( "Menu Option 2", 2 )
      PopMenu.AddItem( "Menu Option 3", 3 )
      PopMenu.AddSeparator
      PopMenu.AddItem( "Menu Option 4", 4 )
      
      ' Show the popup menu (need to use screen coordinates rather than client coordinates)
      dim as long nResult = PopMenu.Show( sender.hWindow, e.x, e.y )
      
      AfxMsg( "You selected menu option: " & nResult )
      
      select case nResult
         case 1
         case 2
         case 3
         case 4   
      end select
   end if
   
   Function = 0
End Function

TreeView Sorting

You can specify that the all nodes in the TreeView are automatically sorted whenever a node is added or inserted into the tree.

frmMain.TreeView1.Sorted = true

If the tree is not sorted, you can manually make a call to the sort method to sort all of the nodes.

frmMain.TreeView1.Sort

If the tree's sorting is False, you can manually sort individual nodes (and their children nodes).

frmMain.TreeView1.GetSelectedNode.SortChildren
' -or-
frmMain.TreeView1.Node(nIndex).SortChildren

Actions on a TreeNode

' Remember, you can retrieve a reference to the TreeNode rather than always having to access the node through the collection
Dim ByRef TreeNode = frmMain.TreeView1.Node(nIndex)

' Set the text for a node
frmMain.TreeView1.Node(nIndex).Text = "New Node Text"

' Set the ToolTip text that displays when the mouse passes over the node
frmMain.TreeView1.Node(nIndex).TooTipText = "This is the tooltip"

' Make the specified node the Selected Node
frmMain.TreeView1.Node(nIndex).Selected = true

' Check the checkbox for the node (if CheckBox style is enabled for the TreeVie)
frmMain.TreeView1.Node(nIndex).Checked = true

' Expand the TreeNode
frmMain.TreeView1.Node(nIndex).Expand

' Expand the TreeNode and all of it's children nodes
frmMain.TreeView1.Node(nIndex).ExpandAll

' Ensure that the TreeNode is visible
frmMain.TreeView1.Node(nIndex).EnsureVisible

' Retrieve the handle to the node (needed if you want to manipulate the node using Windows API functions)
Dim As HTREEITEM hNode = frmMain.TreeView1.Node(nIndex).hNode 

Searching entire TreeView

Because a TreeView is nothing more than a collection of nodes and child nodes, you can use a recursive approach to search the entire TreeView.

function SearchTreeView( byref ParentNode as wfxTreeNode, byval wszSearchText as CWSTR ) as boolean
   ' Do we have a match?
   if ParentNode.Text = wszSearchText then 
      ' Text was matched. Do whatever we need to do to the node.
      ' For example, set the node to be the selected node.
      ParentNode.Selected = true
      ParentNode.EnsureVisible 
      return true   ' cancel any further searching
   end if
   
   ' Recursively search any subnodes of this TreeNode
   for i as long = 0 to ParentNode.Nodes.count - 1
      SearchTreeView( ParentNode.Node(i), wszSearchText )
   next      
   function = 0
end function

' Start our search by iterating the root nodes
dim as CWSTR wszSearchText = "Sub Sub Project File1"
for i as long = 0 to frmMain.TreeView1.Nodes.count - 1
   if SearchTreeView( frmMain.TreeView1.Node(i), wszSearchText ) then exit for
next

Reducing screen flicker

You can reduce screen flicker when adding bulk amount of nodes by wrapping the code in BeginUpdate and EndUpdate.

frmMain.TreeView1.BeginUpdate
   
dim as long root
For i as long = 1 to 10000
   root = frmMain.TreeView1.Nodes.Add("Node #" & i)
Next
   
frmMain.TreeView1.EndUpdate

Canceling an action on a TreeView

Some actions on a TreeView are allowed to be canceled. For example, when navigating from node to node, events are fired. In your code, you have the ability to stop the movement from the current node to the new node. To cancel an action you simply need to set e.Cancel = True prior to returning from the event handler (alternatively, you can set the event handler itself to return False). You can only cancel an action in a "Before" handler.

Examples:

Function frmMain_TreeView1_BeforeSelect( ByRef sender As wfxTreeView, ByRef e As EventArgs ) As LRESULT
   ? "BeforeSelect: "; sender.TreeNode.Text
   e.Cancel = true
   Function = 0
End Function

Function frmMain_TreeView1_BeforeExpand( ByRef sender As wfxTreeView, ByRef e As EventArgs ) As LRESULT
   ? "BeforeExpand: "; sender.TreeNode.Text
   ' e.Cancel = true
   Function = true  ' <-- same effect as e.Cancel = True
End Function

Function frmMain_TreeView1_BeforeCollapse( ByRef sender As wfxTreeView, ByRef e As EventArgs ) As LRESULT
   ? "BeforeCollapse: "; sender.TreeNode.Text
   e.Cancel = true
   Function = 0
End Function

In the above examples, notice the use of the property "TreeNode" of the sender object. This is a special property that represents the TreeNode that is currently being acted upon. This can be different than the SelectedNode TreeNode (especially if a node is being expanded or collapsed programmatically).